EOELAB 运维手册

本文档面向 EOELAB 维护者，说明如何部署、接入和维护本地域、数据设施、认证设施、网络设施及联邦原生设施。账户注册、设备联网和设施使用参见《EOELAB 用户手册》，权限等级和授权设计参见《EOELAB 权限模型》。

阅读导览

• 我要初始化本地域节点并接入统一节点网络 → 本地域节点初始化
• 我要配置计算设施 → 计算设施操作
• 我要设计和分配设施权限 → 《EOELAB 权限模型》
• 我要配置数据设施 → 数据设施操作
• 我要配置认证设施 → 认证设施操作
• 我要配置网络设施 → 网络设施操作
• 我要审核账户或维护联邦节点 → 联邦成员与节点维护
• 我要维护联邦原生设施 → 原生设施维护
• 部署前检查 → 部署检查清单

本地域节点初始化

基础配置

1. 安装 Debian stable + Incus stable（https://github.com/zabbly/incus）
2. 根文件系统使用 Btrfs，并配置 raid1/10
3. Incus 节点主机名使用 DomainPrefix-Number，例如 core0-1
4. 维护者先按《EOELAB 用户手册》获得账户并接入联邦网络，再建立 Incus 或 Ceph 集群
5. 禁用 swap：
   • 安装系统时不创建 swap 分区
   • 执行 swapoff -a 并永久移除 /etc/fstab 中的 swap 条目
6. 仅使用 SSH 密钥登录，关闭密码验证
7. 通过 systemd-timesyncd 同步 UTC，无需额外配置 NTP

计算设施操作

OIDC + OpenFGA 接入

Incus 不再使用 TLS 客户端证书作为用户登录或本地域维护者的鉴权方式。所有用户通过联邦认证设施 Zitadel 使用 OIDC 登录，具体地址参见《EOELAB 服务端点》。Incus Web UI 作为公网管理入口，节点 SSH、实例 proxy 端口和其他节点直连入口只允许通过联邦网络访问。

OIDC 负责确认用户身份，OpenFGA 负责确认用户对 Incus 资源的访问权限。完成 OIDC 登录后，必须在 OpenFGA 中为用户或用户所属组配置关系元组，未配置授权关系的用户不会获得业务资源权限。

对象格式、角色继承、entitlement、最小权限和安全边界统一参见《EOELAB 权限模型》。关系元组的增删和查询在 fgaplane 中完成，具体地址参见《EOELAB 服务端点》。

嵌套 OCI 容器

默认不允许在 LXC 中嵌套运行 OCI 容器。容器部署服务可直接以 OCI 实例运行在 Incus 上，并使用 Incus 网络内部通信。例外：CI/CD 中使用 Kaniko 构建 OCI 镜像。

数据设施操作

存储接口、数据保护策略和驱动选型遵循《EOELAB 互联云架构规范》RFC-0004。

接入 TrueNAS 共享存储

1. 节点命名为 DomainPrefix-nas，例如 core0-nas
2. 计算节点通过其 .eoelab 名称访问存储

接入 Ceph 共享存储

1. 独立节点命名为 DomainPrefix-ceph-Number，超融合节点沿用 Incus 节点名称
2. 节点和客户端使用 .eoelab 名称

认证设施操作

Zitadel 添加应用

• 应用类型：Web
• 响应类型：Code
• 身份验证方式：None
• 授权类型：Authorization Code（启用 Refresh Token）
• 身份验证令牌：JWT
• 重定向：https://<INCUS_UI_PUBLIC_ENDPOINT>/oidc/callback

Zitadel 添加 Action

Incus 需要用户名而不是 sub 长数字序列，因此在 Zitadel 添加以下 Action：

function addUsername(ctx, api) {
  api.v1.claims.setClaim("preferred_username", ctx.v1.getUser().preferredLoginName);
}

触发器设置为“自定义令牌 - Access Token 创建前”。admin 团队已完成全局配置，本地域维护者无需重复创建。

创建 OpenFGA

1. 向 admin 团队申请独立实例，取得实例 URL 和 API Token
2. 打开《EOELAB 服务端点》列出的 fgaplane，为该实例新建 Store 并取得 Store ID

Incus 配置 OIDC

• oidc.audience：留空或填写 Incus Web UI 公网 URL
• oidc.claim：preferred_username
• oidc.client.id：Zitadel Application ID
• oidc.issuer：Zitadel 公共 URL

Incus 配置 OpenFGA

• openfga.api.token：OpenFGA 实例的 API Token
• openfga.api.url：OpenFGA 实例 URL
• openfga.store.id：OpenFGA Store ID

网络设施操作

连接检查

使用 tailscale status 查看连接状态，使用 tailscale ping HOSTNAME.eoelab 验证实际路径。集群和存储节点经 DERP 中继时按降级状态处理。

服务接入

1. Tailscale 是基础网络设施；先为服务配置 .eoelab 节点寻址，再按批准的访问范围提供用户入口
2. 用户入口分为公网和联邦网络两类，不要求同一服务同时提供两类入口
3. HTTP/HTTPS 服务需要向公网用户开放时，向 admin 团队申请 eoelab.org 域名和 Cloudflare Tunnel 路由
4. Cloudflare Tunnel 源站使用 http://localhost:PORT 或 http://HOSTNAME.eoelab:PORT，不配置源站 TLS
5. 只允许联邦网络访问的服务不得配置公网 DNS、Cloudflare Tunnel 路由或其他公网反向代理
6. 联邦内部服务使用 .eoelab 名称和协议的非 TLS 模式，不配置服务端证书或客户端 TLS；例如 PostgreSQL 可设置 sslmode=disable
7. 应用明文流量必须全程位于 Tailscale 或 Cloudflare Tunnel 内，其他路径必须启用协议加密
8. 数据库账户、OIDC、Token、OpenFGA 和 RustFS Policy 等应用认证与授权保持启用
9. Incus Web UI 和 RustFS Console 只提供公网管理入口；Incus 节点直连、RustFS S3 和 WebDAV 只提供联邦网络入口
10. 非 HTTP/HTTPS 服务不得向公网开放

虚拟网络配置

1. 单节点使用 bridge，集群使用 OVN，整个本地域有且仅有一个虚拟网络
2. 用户态接口命名为 INTERFACE-Domain
3. 地址池默认使用 172.16.0.0/12
4. 实例默认接入设备 eth0；VM 需要 proxy 设备时可设置静态地址：

   eth0:
       ipv4.address: 实例静态 IP
       network: 接入网络
       type: nic
   

5. 实例使用 proxy 设备将端口转发到节点，服务接入方式按“服务接入”章节配置：
   • 容器（LXC/OCI）：listen 为外部端口，connect 为内部端口
   • VM：启用 NAT mode，listen 绑定节点的 Tailscale 接口，访问端使用 HOSTNAME.eoelab；connect 的 IP 为实例静态 IP

ACL 配置示例

1. block-host：丢弃主机地址段流量
   • Drop Any 10.0.0.0/8
   • Drop Any 192.168.0.0/16
2. block-internal：丢弃内部地址段流量
   • Drop Any 172.16.0.0/12

联邦成员与节点维护

账户治理

1. 新注册的有效 Zitadel 用户账户自动获得成员身份，不进行事前审核
2. 外部身份提供商创建的账户需要本地密码时，由 admin 团队设置初始密码并通过安全渠道交付
3. 应用管理权限按实际职责分配，不因成员同时是维护者而自动扩大
4. 根据服务日志、成员举报和实际影响判断滥用，不因正常的节点发现和端口连通性预先限制成员
5. 确认扫描、攻击、凭证滥用或资源滥用后，按影响暂停 Zitadel 账户、移除 Headscale 节点并撤销相关 Access Key、Token 或其他凭证
6. 保留处置原因和操作记录；问题解决后由 admin 团队决定是否恢复账户或重新接入节点

节点接入支持

用户按《EOELAB 用户手册》接入网络。维护者需要确认：

• 节点出现在 Headplane 中，所有者与对应账户一致
• 节点使用预期的 HOSTNAME.eoelab 名称
• Headplane 角色符合《EOELAB 权限模型》规定的默认分配和最小权限要求
• 重装或清除 Tailscale 状态后产生的旧节点已安全移除

退出与清理

收到退出申请后，admin 团队执行：

• 与用户确认配置和数据导出范围
• 移除 Zitadel 账户
• 从联邦网络移除节点
• 回收联邦权限并清理相关数据
• 对本地域协助导出联邦设施配置、交付必要数据并移除设施接入

长期失联或存在安全风险的节点可以强制移除，但应保留操作记录。

部署 DERP 中继节点

1. 从《EOELAB 服务端点》取得 Headscale 地址，下载客户端并登录：

   HEADSCALE_ENDPOINT='<HEADSCALE_ENDPOINT>'
   tailscale login --login-server "$HEADSCALE_ENDPOINT"
   

2. 使用以下 Docker Compose 部署 DERP，并放行 3478/UDP 和 12345/TCP：

   services:
     derper:
       image: ghcr.io/yangchuansheng/derper:v1.98.8
       ports:
         - 3478:3478/udp
         - 12345:12345
       environment:
         DERP_DOMAIN: example.com
         DERP_CERT_DIR: /cert
         DERP_ADDR: ':12345'
         DERP_STUN_PORT: '3478'
         DERP_HTTP_PORT: '-1'
         DERP_VERIFY_CLIENTS: "true"
       volumes:
         - ./cert:/cert
         - /var/run/tailscale/tailscaled.sock:/var/run/tailscale/tailscaled.sock
   

3. 向 https://codeberg.org/eoelab/Derpmap 提交 PR 增加节点：
   • 区域代码为 chn（ISO 3166-1 三字母规范），区域名称使用国家全称
   • 中国大陆（chn，ID 为 900）只接收来自中国大陆的中继节点，港澳台除外
   • 建议启用客户端验证避免滥用

不接受自签名节点，必须包含公共 CA 证书；中国大陆云服务器必须使用备案域名作为入口点。

原生设施维护

注册自托管 Runner

1. 接收用户按《EOELAB 用户手册》提交的 Codeberg Runner UUID 和 Token
2. 将连接名称 forgejo 替换为申请人的用户名，避免同名 key 冲突
3. 将 Runner 接入隔离的执行环境，不向用户工作负载暴露其他用户凭证或宿主机管理接口
4. 完成注册后通知申请人验证 Job 调度

使用监控设施

1. 将服务设备命名为 monitor 并接入联邦网络
2. 部署 Prometheus 和 Thanos Sidecar，将历史指标上传到 oss
3. 配置外部标签 cluster=eoelab 和 replica=monitor
4. 部署 Thanos Query、Store Gateway 和 Compactor；同一存储桶只运行一个 Compactor

部署检查清单

本地域节点

• 安装 Debian stable + Incus stable
• 根文件系统使用 Btrfs，并配置 raid1/10
• Incus 节点主机名使用 DomainPrefix-Number 格式，独立存储节点使用对应的角色命名格式
• 建群前已接入联邦网络，并使用 HOSTNAME.eoelab 配置集群
• 禁用 swap
• 仅使用 SSH 密钥登录，关闭密码验证
• 确认时间通过 systemd-timesyncd 同步 UTC

数据设施

• 根据单机/小中/大超大规模选择 Btrfs / TrueNAS / Ceph
• 统一存储接口命名格式 <接口>_<介质><容量><性能>
• 热数据使用多副本；温/冷数据使用 RAID-Z 或 EC
• 多节点场景优先计算与存储分离

网络设施

• 集群和存储节点保持直连，DERP 中继已纳入降级监控
• 单节点用 bridge，集群用 OVN
• 配置 ACL 阻止实例访问底层私网
• 公网 HTTP/HTTPS 服务通过 Cloudflare Tunnel 暴露，源站使用 localhost 或 .eoelab HTTP 地址
• 服务的公网或联邦网络访问范围与《EOELAB 服务端点》一致
• RustFS S3、WebDAV 和 Incus 节点直连没有公网 DNS、Tunnel 路由或公网反向代理
• Incus Web UI 和 RustFS Console 公网入口未被内部自动化作为服务间通信地址
• 应用明文流量未离开 Tailscale 或 Cloudflare Tunnel
• 应用认证与授权未因省略 TLS 而取消
• 非 HTTP/HTTPS 服务只允许通过联邦网络访问

监控设施

• monitor 已接入联邦网络，并通过 .eoelab 名称采集目标
• Prometheus 已配置本地 WAL、短期保留和唯一外部标签
• 实时告警与历史指标告警已分别配置到 Prometheus 和 Thanos Ruler
• 每个 Thanos 或 Loki 数据集只有一个 Compactor
• RustFS 已通过 Thanos 和 Loki 的对象存储兼容验证
• Alertmanager 实例具备本地持久化并已完成 Gossip 互联

联邦接入

• Zitadel 自助注册可正常创建成员账户并接入联邦网络
• 已验证账户暂停、Headscale 节点移除和应用凭证撤销流程
• 节点所有者已按《EOELAB 用户手册》完成 Tailscale 接入
• 节点名称和所有者信息正确
• 需要 DERP 时已按部署配置提交 PR 至 Derpmap

Post list